Skip to main content

Writing component documentation

#1 Do some homework​

Start by looking at how other folks document the same or similar components. Feel free to borrow from their wording as it makes sense.

Good example: An overflow menu is used to convey at least two actions for a card or list item. This component helps users understand discrete actions that are related to the specific item from where they are launched, without affecting the whole screen.

Example that needs work: Menus are used for items that have various options. Users like to select two options.

App resources​

VA & Government resources​

Other resources​

#2 Write a draft following the template​

Now that you’ve done a bit of homework, start writing a draft. Our component documentation template is aligned with how the VA.gov design system documents components. The sections include:

  • Purpose
  • Examples
  • Usage
    • When to use the component
    • When to consider something else
    • How the component works
    • Behavior
    • Choosing between variations
    • Placement
    • Design principles
    • Instances of the component in production
  • Code usage
  • Content considerations
  • Accessibility considerations
  • Related components

As you work on your draft, feel free to reference our existing components on the documentation site.

Note: If you prefer to start working in Google Docs, we have a template for that as well.

#3 Review and submit the ticket​

Once you’ve completed your draft, share it with a teammate to review. When you’re ready to publish the documentation, tag the Design System product manager in the ticket and they’ll assign it to the team to review your documentation.

Your documentation will typically be reviewed by a designer, engineer, content designer, and accessibility specialist. If the team has any questions, they’ll reach out to you directly. If it looks good, they’ll publish your documentation.

Need help?​

If you have questions along the way, reach out to the Design System team in Slack.